
Help Files Help 

                                               version: 1.4
                                               created: 07/17/2000 {12:22:13 pm}
                                           last update: 10/29/2001 {17:17:31 PM}

	  	Introduction

This document deals with two different topics.  The first describes how
users can obtain help for AlphaTcl's modes and features using various
facilities built into the program.  The second is more technical, intended
for developers working on AlphaTcl's documentation, explaining AlphaTcl's
auto-marking / hyperizing routines for Help files.

There are several different listservs set up to support AlphaTcl's
continuing development and use, including one devoted to updating Help
file documents and the methods used to find Help topics.  See the "Readme" 
file for more information.
	  	
	======================================================================

	  	Finding Help for specific Topics

Note that in this file (as well as other Help documents) 'Alpha' generally
refers to applications Alpha or Alphatk, while 'AlphaTcl' refers to the
library of modes, menus, and other packages which extend the program's
capabilities.

Many help files include a variety of hyperlinks which can either open up
another help file, such as the "Packages" link, or will evaluate some
internal procedure (usually opening some sort of dialog) such as this one:
<<suffixMappings>>.  In this case, clicking on the hyperlink is equivalent
to selecting the "Config --> Preferences --> Suffix Mappings" menu item.

Other hyperlinks such as "Macros Example" will open an interactive tutorial
allowing you to explore the various features of a package.


	  	 	Using the Help Menu

The first place to check for help for a given topic is usually the 'Help'
menu which appears in the menu bar following all of the other menus
currently active.  Selecting an item from this menu will usually open a
file contained in Alpha's 'Help' directory, although some (such as the
"Alpha/tk Home Page") will send a url to your local browser, or offer you a
list of other options.  

If the question that you have is more specific, you might also try the
"Alpha Manual", or the shorter "Quick Start".


	  	 	Help File Formats

Most of AlphaTcl's documentation can be opened within Alpha.  In some cases,
.html or .pdf versions of these files are available as well.  Setting the
"Config --> Preferences --> Help" preferences, (also available by clicking
here: <<dialog::preferences preferences Help>>) allows you to determine
your preferred help file format.

In addition, .html files can be sent to either a local browser or parsed
internally by Alpha using the WWW Menu.  Set your "WWW" preferences to your
preferred method (<<dialog::preferences preferences WWW>> and then try
opening the "Electric Corrections Help" file to see the difference.  For
more information about the WWW Menu, click here: "WWW Help".


	  	 	Mode Specific Help

Pressing <control-Help> will always open any available help for the mode of
the current window.  The "Config --> Mode Prefs --> Descrihe Mode" menu
item provides more technical information regarding the mode, including the 
Tcl code used to create some of the mode's key bindings.

Many modes allow you to customize their behavior by setting 'Mode Prefs',
which can be accessed using the "Config --> Mode Prefs --> Preferences"
menu item.  These dialogs generally include a 'Help' button that describe
the preferences is greater detail.


	  	 	Other 'Help' Options

In addition to the 'Help' menu, Alpha contains several other methods to
obtain help.  The "Config --> Packages" menu contains items for "Describe a
Package" and "Read Help for a Package".  Selecting either of these will open
a dialog allowing you to select the package for which you want more
information.  The "Packages" help file also contains a wealth of hyperlinks
which will open any available help for the packages listed.

Some modes and packages also create 'Help' menu items once they have been
activated, or insert preference pages in the "Config --> Packages" menu.


	  	 	Bindings Help

One of Alpha's strongest features is the ability to bind nearly any key
combination to a specific menu item or action.  The "Default Key Bindings"
help file contains more information on how you can find out what a
particular key is bound too, as well as how to create your own personalized
set of key bindings.

	----------------------------------------------------------------------

The remainder of this document is devoted to creating Help files for Alpha.

	======================================================================


	  	Auto Marking Help Files

AlphaTcl v 7.4 introduced auto-marking / hyperizing capabilities for Help
files.  If a file that contains no colors is opened through the Help Menu,
AlphaTcl will go through a series of hyperizing / marking routines using
help::colourHeadingsEtc (in "help.tcl").

Auto-marking / hyperizing files must be "clean" before they are opened
through the Help menu -- that is, they must not have any colors or hypers
in them.  If this is the case, AlphaTcl will mark the file and perform a
series of "search and hyperize" routines following the guidelines below.

These routines makes writing Help files much easier -- no need to
individually "Link To File" anymore !!  (This means that help files can
also be marked and hyperized by Alphatk.)

In the MacOS, Help files will only be auto-marked / hyperized once, and then
the hypers will be saved in the resource fork.  (Note: This will not change
the "save" date of the file.  Installation of future versions of AlphaTcl can
still overwrite older existing files.)

See these "Alpha Developers --> Marking" menu item procedures for details
on what these auto-marking / hyperizing routines actually do:

    proc: help::hyperiseEmailAddresses
    proc: help::hyperiseUrls
    proc: help::colourHeadingsEtc

The proc: help::openDirect uses these procedures, setting additional window
information (read-only 1, dirty 0, tabsize 4).  The Help file is then
closed and re-opened.

The following sections describe the syntax required to achieve marks, 
hypers and colors in these files.  Note:  there is an additional marking 
regime, proc: help::markTclCommands, that might be used instead for 
particular files.  See the "Exceptions" section below.


	  	 	Marks

To create a mark, start the line with <tab><space><space><tab>.  This will
be stripped from the mark name.  Subsequent spaces and tabs will indent the
mark's name, which is useful for sub-sections.  (Note that a tab will
indent only one space.)  To insert a section divider, include a line that
contains only = signs, optionally preceded by whitespace.

Note that the proc: help::openDirect will automatically convert tab sizes to 4.


	  	 	Help File Marking Exceptions

There is an alternative marking routine, proc: help::markTclCommands, that
is used in place of help::colourHeadingsEtc for certain files.  See the
proc: help::openFile for a list of the exceptions.

These files will still hyperize e-mails and urls, but marks are based on any
word which follows the string NAME, where NAME is the first word encountered
on a line.  (See "Tcl Commands" for an example.)  Hyperlinks to additional
files, however, are not possible.  The only additional coloring provided is
for lines which contain ALL CAP WORDS, and the file's "title".

(The "Alpha Commands" file has it's own marking procedure as well, using
proc: help::markAlphaCommands, which can not be used for any other file.)

Important: Both of these routines only apply to Help files in Text mode.


	  	 	Colors
		
Any line that begins with one (and only one) tab will be colored blue,

	like this.  Subsequent lines that begin with a tab
		will be colored blue as well.

The string IMPORTANT: will be colored red, as will menu directions that
include "<something>-><something>":

    "File --> Open..."

    "Config->Preferences->Suffix Mappings"

    'Text -> Fill Paragraph'

    'Alpha Developers Menu --> Marking --> Colour Headings Etc'

Several variations are allowed, so long as <something>-><something> is
surrounded by either single or double quotes.


	  	 	Examples and Tutorials

Most of Alpha's help files are contained in the 'Help' directory. 
Example files, however, are in the 'Examples' directory.  Feel free to
contribute additional example files, which can be accessed by hyperlinks
(see "# Hyperlinks to Examples" below), menu items (as in the Filters
and the Mac Menu packages), or by hyperlinks in the "Examples Help"
file.  (This last has to be updated manually -- see the notes at the
bottom of that file for more information.)

'Completion' tutorials are kept in the 'Tcl:Completions' folder, and can
be accessed by the "Config --> Mode Prefs --> Completions Tutorial" menu
item, hyperlinks in the "Packages" help file, or by hyperlinks created
in other help files.  (See the "# Hyperlinks to Installed Files"
sections below.)

A word about Example and Completion Tutorial filenames:

Example files should use suffix mappings to properly open the window in 
the desired mode.  If the file has 'Smart Line', like this:

	-*-Setx-*-

then that will be used preferentially.  The actual filename doesn't
matter as of this writing:  "Setx-Example.stx" and "Setext-Example.stx" 
will be treated the same.  (Only the second file is actually installed, 
so the first hyperlink won't work.)

Completion tutorials, however, must follow a different set of rules. 
These files MUST begin with the exact name of the mode, followed by the 
string ' Tutorial'.  The file suffix in this case doesn't matter.  Here
are a few examples:

	"M2 Tutorial.m2"
	"Bib Tutorial.bib"
	"C++ Tutorial.cc"

Note that these file name syntax rules are subject to both debate and
change as Alpha's Help files and routines undergo more extensive updating
and revision -- watch this space for more details.


	  	 	Hyperlinks

Hyperlinks are created by the proc: help::colourHeadingsEtc, contained 
in "help.tcl".


	  	 	 	Hyperlinks to Window Marks

Any mark in the current window can be hyperlinked by using an 'anchor'
syntax, preceding the mark's name by '#' and surrounding it with double 
quotes, as in "# Hyperlinks to Examples".  It is not necessary to
compensate for any extra spacing that might occur in setting the actual 
mark name.


	  	 	 	Hyperlinks to Installed Files

To create a hyperlink to most .tcl files, include the file's name in quotes:

    "htmlMode.tcl"

To create a hyperlink to most Help files, include the file's name in quotes:

    "Extending Alpha"    "Alpha Manual"    "Calculator Help"

Help for specific packages can be hyperlinked in two ways.  The first is to
precede the package's name with 'package: ', as in package: latexAccents.
The second way is to surround the package's name in quotes, and add ' Help'
as in "recentDirsMenu Help".  Thus the BibTeX help file could be hyperlinked
with all of

    "BibTeX Help"    package: Bib    "Bib Help" 
    
    package: bibtexMenu    "bibtexMenu Help"

Completion files and Completion Tutorials can also be hyperlinked:

    "TclCompletions.tcl"  "Text Tutorial"  "C Tutorial.r"  


	  	 	 	Hyperlinks to Examples

To include an 'example' hyperlink, which will open any file in the Mode
Examples folder in read-only format, simply put the file's name in quotes:

    "LaTeX-Example.tex"

To open the example in a shell window, which will insert some explanatory
comments at the top of the window and allow for any modifications without
altering the original file, omit the dash preceding Example in the file's 
name:

    "LaTeX Example.tex"

Note that examples which are opened in shell windows do not technically 
exist as files, and the window will not have any file suffix.  This could 
disable some mode features that rely on file suffixes, and the window can 
not be sent to other applications.

If you want to include an example that does something different than these
two default routines, you must create a "<something>-Example.sfx.tcl" file. 
The AlphaTcl-specific modes use such scripts (i.e. "Compare Example" sources
"Compare-Example.tcl").  These can also be adapted for package-specific
tutorials, such as the tutorials

    "Filters Example"       "Filters-Example.tcl"    and
    "ManipCols Example"     "ManipCols-Example.tcl"

See some of the .tcl files in the 'Examples' folder for more examples.


	  	 	 	Hyperlinks to Prefs Files

The proc: help::colourHeadingsEtc recognizes "<mode>Prefs.tcl" strings.
Thus I can include the following lines in my "Statistical Modes Help" file:

	----------------------------------------------------------------------

To add keywords in a "SASPrefs.tcl" file, include the following commands:

	set SASuserCommands {
	    blah blahdity etc
	}
	
	----------------------------------------------------------------------

Clicking on the "SASPrefs.tcl" link will prompt the user to create the 
file if necessary.  The string "prefs.tcl" will similarly open the global 
preferences file.


	  	 	 	Hyperlinks to Hypertext

Strings embedded in << >> will be treated as hypertext.  For example,

    <<WWW::renderFile [file join $HOME Help "Electric Corrections Help.html"]>>

will send the 'Electric Corrections.html' file to the WWW Menu for parsing.

    <<suffixMappings>>

will open the "Config --> Preferences --> Suffix Mappings" dialog.


	  	 	 	Hyperlinks to Tcl Command Double-click

When a file is in Tcl mode, command double-clicking on a defined procedure
will open the file in which that proc is contained.  In Help files, the
string proc: <something> will create a hyperlink which does the same, as in

    proc: Tcl::DblClickHelper

Very handy for AlphaTcl developer help files !  This will also work for
AlphaTcl or Tcl commands, as in proc: regModeKeywords or proc: proc .

(An alternative hyperlink "hint" is "command: ", as in command: append or
command: abbrev .  Note that proc: <string> and command: <string> do the
exact same thing, following the orders of precedence in Tcl::DblClickHelper.)


	  	 	 	Hyperlinks for Web Applications

Finally, email and url addresses surrounded by <> will be hyperized as 
well, as in <http://www.alpha.olm.net/> or <cupright@princeton.edu>.

	----------------------------------------------------------------------

	  	Tools for Auto-Hyperizing Files

Using the guidelines outlined above, any "clean" Help file opened through
the Help Menu will auto-mark / hyperize using the routines defined in the
Alpha Developer's Menu.  In the MacOS, the window's "dirty" information for
will then be set to "0", then the file will close and reopen.  (See the
proc: help::openFile for details.)

To color and mark files, or to remove hypers, use the menu items found in
"Alpha Developers --> Help File Marking".  Note that any files uploaded to
the AlphaTcl CVS will be distributed free of all hypers, marks and colors,
so please check all of your auto-marking help files before releasing them!

	----------------------------------------------------------------------


	  	Building the AlphaTcl Help Menu

Items in the Help menu are added only if there is a valid file located in
the Help file in the top level of the Alpha hierarchy.  All file extensions
are stripped from the name, and no duplicates are added.  For example, if
the Help folder includes

	Electric Corrections Help
	Electric Corrections Help.html

only "Electric Corrections Help" is listed, but when the user tries to open
it a list-pick dialog opens with both of them.  AlphaTcl can currently send
.html .pdf and .tex files to the appropriate helper application, using the
proc: help::openDirect AlphaTcl will also present the user with .html file
viewing options.

There are several "Help Menu" preferences that can help limit the options
presented to the user, as described above.  If there is only one file, or if
the preferences narrow down the options to only one format, it is sent
automatically to the proc: help::openDirect.


	  	 	Exceptions -- .tcl files

If there is a .tcl file associated with the Help menu item, such as a "TclAE
Help.tcl" file, this file is immediately sourced.  It is up to the script to
decide if more options will be presented to the user -- the script can
choose to ignore the Help Menu preferences or not.  See the "HTML Help.tcl"
or "LaTeX Help.tcl" files for more examples.


	  	 	Subdirectories in the Help folder

In versions of Alpha/tk prior to 8.0, the name of any subdirectory in the
Help folder is simply listed as another menu item.  If there is no .tcl
file associated with the menu item, selecting it will offer the user a
list-pick dialog of all items within the subdirectory using the "Help Menu
Options" preferences mentioned above.  

In versions 8.0, the name of the subdirectory will be inserted as a submenu
listing the contents of the folder, unless there is an associated .tcl file
present.  In this case, the item will simply appear as another option (as
above), and selecting it will immediately source the .tcl script.

So in both versions, if the help file for a particular feature / mode etc
is a complex .html suite (like the HTML mode manual), including a
subdirectory named (for example)

	HTML Help

as well as the script

	HTML Help.tcl

will simply insert "HTML Help" in the Help menu, but allow its selection to
do whatever the script wants, including opening any of the files within the
HTML Help subdirectory.

	----------------------------------------------------------------------


	  	Documenting Help Files

Every Help file is a work in progress.  AlphaTcl's features change, and 
documentation that might seem perfectly clear to the programmer might 
make less sense to a user.  I recommend the following guidelines for 
ensuring that documentation can (and will) be regularly updated:

	(1)	Include version numbers on all help files.

Ideally, this number would correspond to the version number of the mode / 
feature / menu / extension etc.  explained in the Help file.  This way 
future programmers and users will have a much better idea of when a Help 
file might need to be updated.

	(2)	Use the Document Projects feature when writing Help files.

This feature allows for files to automatically update "save" dates in the 
header.  See the "Documentprojects Help" file for more information.

	(3)	Include author / maintainer information for Help files.

The author of the package is not necessarily the author of its associated
Help file, and neither of these might be the person who is currently
updating or maintaining the Help file.  Please give credit where it is due,
and include information on where one can send suggestions on the Help file. 
This will make updates much more likely to occur.

	(4)	Include any license and disclaimer notes somewhere in the file.
	
	======================================================================


	  	Copyright

This document has been placed in the public domain.

Feel free to send me any bugs, comments, or suggestions on this file.

cheers,

-- cbu

Author: Craig Barton Upright
E-mail: <cupright@princeton.edu>
  mail: Princeton University,  Department of Sociology
        Princeton, New Jersey  08544
   www: <http://www.princeton.edu/~cupright/>

